The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/umich/telecomm/shadow11.arc/README.11

Text File | 1988-10-30 | 16.9 KB | 431 lines

SHADOW version 1.1 Enhancements
================================

Most of the enhancements in SHADOW version 1.1 are not available from within
Flash 1.6. Most notably Flash 1.6 cannot find SHADOW when SHADOW is installed
in the NON RESET-PROOF mode. The next version of Flash will incorporate all the
new features. In the meantime, all of the features are usable when SHADOW is
run as an accessory or a GEM program.

SHADOW Accessory
================

The SHADOW desk accessory is renamed from SHADOW.ACC to SHDW_ACC.ACC to avoid a
name conflict when the desk accessory is used as a GEM program.

By renaming SHDW_ACC.ACC to SHDW_ACC.PRG, you can run the SHADOW accessory
as a GEM program, thereby allowing you to access SHADOW without having the
desk accessory installed all the time.


NON RESET-PROOF MODE
====================

SHADOW can now be installed as NON RESET-PROOF.  When installed this
way, SHADOW only reserves enough memory for the transfer handler, not
the transfer buffer. When a transfer is desired, you allocate the size
of the buffer you need.  When the transfer is completed, you can
deallocate the memory used for the transfer buffer.

To install SHADOW as a NON RESET-PROOF handler, simply specify a RAMdisk
and transfer buffer size of zero (0) in your SHADOW.INF file, on your
desktop icon, or on startup using the 'on the fly' startup keys.

If SHADOW is installed this way, you will be prompted for the file transfer
buffer size before each file transfer, unless the buffer remains intact
from a previous transfer (i.e., it has not been deallocated).  If the
transfer buffer is intact, you will not be prompted, but you can still
change the size (see "Changing Options" below).

You can also install SHADOW with a RAMdisk and no transfer buffer.  When
installed this way, you have a RESET-PROOF RAMdisk, but the transfer buffer
is NON RESET-PROOF.  You will be prompted for the transfer buffer when you
start a transfer, and you can alter the transfer buffer size (see "Changing
Options" below).

NOTE:
    You CANNOT allocate a transfer buffer from the SHADOW accessory being
    run as a program when the handler is installed with the SHADOW RAMdisk.
    You CAN allocate a transfer buffer if allocating from the desk accessory.

NOTE:
    When you have SHADOW installed as a NON RESET-PROOF handler, it will
    be erased during a reset. All data in the buffer will be lost. DO NOT
    press the reset button unless you don't mind losing the data in the
    transfer buffer!


Changing Options
================

Three new options are configurable from SHADOW, these are the current timeout
value, the buffer size (NON RESET-PROOF mode ONLY), and the on-screen
counter location.

To get to the Options menu, click on the transfer buffer size button from
the main menu (contains text such as 100K) or press the 'O' (Options) key.
While in the terminal mode press the ALT-O keys simultaneously.

NOTE:
    Version 1.01 used 'W' (Wait) for this button from the main menu,
    this version uses 'O' (Options) instead.

You will be presented with a dialog box asking you 'Choose What to Set,'
with three buttons to select:

Timeout         - click on this to set the current timeout value.  You will
                  be presented with a dialog box asking you to 'Enter New
Can also be       Timeout.'  Enter the new value in seconds.  You cannot
accessed by       enter below 10 seconds.  Click on Okay, or press the
pressing          letter 'O' key, or <RETURN>.  Press the right mouse button
the 'T' key       or <UNDO> key to not set the value.


Buffer Size     - click on this to set the transfer buffer size.  The top
                  line will tell you the 'Largest Memory Blk' (block) in
Can also be       Kilobytes that you can allocate.  If you currently have a
accessed by       buffer allocated, its size will be indicated on the second
pressing          line.  It is possible (if memory is not fragmented) that
the 'B' key       you can add the two values together to compute the
                  maximum available free memory.  To truly determine the
                  maximum free memory, enter a buffer size of zero (0),
                  press the <RETURN> or 'O' key or click on the Okay button.
                  Choose Buffer Size again.  At this point, the top line
                  WILL indicate the maximum free memory available for the
                  transfer buffer.  Enter the desired buffer size in Kbytes.
                  If you are in the process of a transfer or have a file(s)
                  waiting to be received/sent you will not be able to
                  select this option.  You CANNOT select this option if you
                  are in RESET-PROOF mode.

            NOTE: If you execute the SHADOW accessory as a program, you
                  CANNOT allocate a transfer buffer from the program when the
                  SHADOW RAMdisk is installed.


Counter Location- click on this to set the on-screen counter location.  When
                  you click on this button, a box will appear in the current
Can also be       counter location with the text '9999/9/99' in it.  Position
accessed by       the mouse over the box, press the left mouse button and
pressing          while keeping the left mouse button depressed, drag the
the 'C' key       outline box (which appearred when you pressed the mouse
                  button) to the desired screen location.  The new counter
                  location will appear in the place you just chose.  You may
                  continue to do this until you get the counter positioned
                  where you like it.  Press the RIGHT MOUSE button to exit
                  this mode and return to the Options menu.

Press the RIGHT MOUSE button or <UNDO> key to exit the Options menu.


SHADOW.INF
==========

SHADOW.INF save now deletes any existing SHADOW.INF file before trying to
create a new one. This is to work around an OS bug which sometimes caused
two SHADOW.INF files to be in the AUTO directory.

SHADOW.INF now contains an extra line which contains the location for the
on-screen counter location.  The line looks like:

L071,024

where 071 is the x value in character coordinates and 024 is the y value.
This value will be read by the SHADOW accessory to set the location.  The
default location is in the upper right hand corner.

NOTE:
    RESAVE your SHADOW.INF file to include all current values.


Hangup String
=============

Pressing ALT-H in the terminal will now send out a hangup string.  The
hangup string is configurable from the dialer menu.  Here is how to configure
the hangup string.

For a HAYES compatible modem, a typical hangup string might look like this:

        %(1)+++%(2)ATH|

This string will delay for 1 second, send out '+++' to the serial port,
delay for another 2 seconds, then send out 'ATH' followed by a carriage
return.

To delay for up to 32767 seconds, you MUST enter a string in the HANGUP
field with the syntax of:

        %(seconds)

where seconds is a whole positive number of seconds to delay.

Any text after the above construction will be sent after the delay.  To send
a '%' out, enter %% in the hangup field.

A vertical bar '|' will be substituted with a carriage return.

This hangup string will be saved in your .MDM file.  You MUST resave your
directories to have this string load when you load a directory.  Old SHADOW
directories are 100% compatible with this addition.


Terminal
========

If you are currently dialing, ALT-A from the terminal will abort the dialer.

Pressing F3 would sometimes act like it was not being pressed, resulting in
the need to press it until the abort message came up.  This is fixed.

Answering 'N' to abort transfer before the transfer begins will now redraw
the status line.

When receiving Y-Modem Batch, the expected file size will also be displayed
in the status line, but only if the sender sends the file size in the
startup packet.

ALT-O brings up the Options menu (see above).


Transfer Status
===============

The status line has been greatly enhanced.  If you are running the terminal
in medium or high resolution, you have a lot more information during file
transfers.  A typical status line during a file transfer might be:

-----------------------------------------------------------------------------
 Receiving FILENAME.EXT | Block 5/2 | Size 12345  Recv'd 2048 | File 2
-----------------------------------------------------------------------------
 or
-----------------------------------------------------------------------------
 Sending FILENAME.EXT | Block 5/2 | Size 12345  Sent 2048 | File 2 of 7
-----------------------------------------------------------------------------
  ^        ^                  ^ ^        ^           ^      ^
  |        |                  | |        |           |      |
  |        |                  | |        |           |    Current File
  |        |                  | |        |           |    (1 for non Y-Batch)
  |        |                  | |        |           |
  |        |                  | |        |      Bytes sent/received thus far
  |        |                  | |        |
  |        |                  | |  Actual size (???? for non Y-Batch Receive)
  |        |                  | |
  |        |                  | Retry count
  |        |                  |
  |        |              Current Block
  |        |
  |      Current Filename (All sends; protocol for non Batch or
  |                                                non B-Protocol receive)
 Current direction

Low resolution will have just the Direction, Filename/Protocol,the Actual
file size, and Bytes sent/received thus far.

The dialog box displaying current file status (displayed when you select
SHADOW from the DESK menubar during a transfer), now looks like:

        +------------------------+
        |  FILENAME.EXT   12345  |
        |------------------------|
        | Block = 10/2 | File 1  |
        |------------------------|
        |       +-------+        |
        |       | Abort |        |
        |       +-------+        |
        +------------------------+

where:
        FILENAME.EXT    is the current file being sent or received, or the
                        protocol in non Y-Batch or non B-Protocol receives.

        12345           is the actual file size expected on Y-Batch receives,
                        bytes received thus far for non Y-Batch receives,
                        bytes to send for all sends.

        Block = 10/2    is the current block (10) and retry count (2) for
                        the current block.

        File 1          is the current file being sent or received, always
                        one (1) for non Y-Batch protocols.


.TOS or .TTP file status display has also been greatly enhanced.  A typical
display (defaults to upper right hand corner) might be:

3   /2/5
^    ^ ^
|    | |
|    | Current file being sent or received (always 1 for non Y-Batch)
|    |
|  Retry count for current block
|
Current block being sent/received

Additionally, periodic messages might be displayed during the transfer:

RESENDING   - other end requested retransmission of current block
TIME OUT    - a timeout condition occurred; retry block
SUM ERROR   - a checksum/CRC error occurred on current block; retry block
FILE OKAY   - file received OK during Y-Modem batch

The message will appear for approximately one second instead of the block
counter, then the block counter will be redisplayed.

The method used to display the digits has changed.  You will now notice a
'strobe' effect if the screen is redrawn.


Handler
=======

Two calls have been added to the SHADOW routines.  These calls will
return the current version number and set the current on-screen counter
location.  See 'Programmers' below for calling procedure.  Additionally,
the current routines have been modified to detect the NON RESET-PROOF
handler.  See the SHDWACES.S file for the new calls and changes to existing
SHADOW calls.

EOT detection has been enhanced to help weed out false EOTs.

On Y-Modem Batch receives, the expected file size is checked against the
remaining buffer size.  If the file is too large, the transfer will abort
with the message "Buffer Full" before the transfer of that file is started.

The background auto-dialer will now only check for characters up to ASCII
value 127.  You can enter values greater than that in the strings, but they
will cause the string to be never found.

The RAMdisk handler has been reworked to tweek more speed out of it and
allow for large RAMdisks.


Programmers
===========

For programmers, two calls have been added to SHADOW.  One to retrieve the
current handler version, and the other to set/get the current on-screen
counter location.  These are routines number 11 and 12 (see owner's
manual, Appendix A)

Routine #       Name
---------------------------------------------------------------------------
     11         shdw_version -> return the current handler version
     12         shdw_location-> set/get current on-screen counter location

Here is the 'C' level bindings written in Megamax C:

int shdw_version()
{
  asm {
    move.w #11,-(A7)
    trap   #15
    addq.l #2, A7
  }
}

Using this call will return a decimal value equivalent to the current
version, such as 110 (one hundred ten) for version 1.1

Use as such:

    version = shdw_version();

Older versions of the handler will return the function number (11).

NOTE:
    Any illegal function call will return the number passed as the
    function number.  This applies for all versions.


int shdw_location(x,y)
int x, y;
{
  asm {
      move.w y(A6), -(A7)
      move.w x(A6), -(A7)
      move.w #12, -(A7)
      trap   #15
      addq.l #6, A7
  }
}

Pass x and/or y in character coordinate values to set that coordinate.
Passing a -1 for the x coordinate will return the current on-screen location
of the x coordinate in the upper byte of the lower word of D0.
Passing a -1 for the y coordinate will return the current on-screen location
of the y coordinate in the lower byte of the lower word of D0.

For example, calling shdw_location(-1,-1) would return in D0:

|  High    Word |  Low     Word |
+-------+-------+-------+-------+
|   0   |   0   |   x   |   y   |
+-------+-------+-------+-------+


SHADOW Structure
================

In addition, version 1.1 has two more records added to the SHADOW internal
structure.  These records will contain the current ASCII string file length
for the current Y-Modem batch file being received, and an integer value of
the current retry count.  Here is the new record:

typedef struct SHDW_STRUCT {
    int     block,          /* current transfer block */
            status;         /* current status, defined in Appendix A */
    long    rec_bytes,      /* bytes received thus far */
            sent_bytes;     /* bytes sent thus far */
    int     num_files;      /* number of files to send or recieved */
    long    b_bytes[32],    /* batch file sizes, 32 max */
            b_files[4*32];  /* batch file names (on 4 long boundary) 32 max */
    int     digit_flag,     /* on-screen digits? 0 = no, 1 = yes */
            bell_flag,      /* completion bell? 0 = no, 1 = yes */
            mode,           /* transfer mode (0-5, defined in Appendix A) */
            type,           /* transfer direction, 1 = receive, 2 = send */
            dial_flag;      /* dialing? 0 = no, 1 = yes */
    char    bfile_len[10];  /* ASCII string: expected length of BATCH file
                                now being received */
    int     retries;        /* current retry count for above block */
};

In conjunction, the new call (version) with the structure change will allow
for enhanced file transfer reporting, while still maintaining downward
compatibility with pre-version 1.1 releases.


Directories
===========

The last directory path used for a SHADOW send or receive will be remembered
for the next transfer.  Previously, the current path was used, despite the
previous path.


Default Buttons
===============

Almost every dialog box now has a default button which can be selected by
pressing the <RETURN> key.  A default button is denoted by a larger border
than the other buttons.  For example, the Save/No Save dialog box has a
default button of Save, and may be selected by simply pressing <RETURN>.
All one button dialog boxes have the one button as the default.

NOTE:
    You may still press the FIRST letter of mostly all buttons to select
    that button.  Refer to you owner's manual for more information.


Aborting
========

Aborting from the status dialog box will now delay for one second, then
reappear with:

        - An alert box reporting "Aborting Transfer"
        - A dialog box indicating "Transfer Complete. Save|No Save"
        - The main menu